protocol

Default timeout in seconds for one sync grep phase.

Timeout in seconds for the async grep wrapper.

This gives FilesystemBackend enough headroom to finish the worst-case sync path: ripgrep timeout, then Python fallback timeout.

Standardized error codes for file upload/download operations.

These represent common, recoverable errors that an LLM can understand and potentially fix:

• file_not_found: The requested file doesn't exist (download)
• permission_denied: Access denied for the operation
• is_directory: Attempted to download a directory as a file
• invalid_path: Path syntax is malformed or contains invalid characters

Check whether a backend class's execute accepts a timeout kwarg.

Older backend packages didn't lower-bound their SDK dependency, so they may not accept the timeout keyword added to SandboxBackendProtocol.

Results are cached per class to avoid repeated introspection overhead.

Result of a single file download operation.

The response is designed to allow partial success in batch operations.

The errors are standardized using FileOperationError literals for certain recoverable conditions for use cases that involve LLMs performing file operations.

Result of a single file upload operation.

The response is designed to allow partial success in batch operations.

The errors are standardized using FileOperationError literals for certain recoverable conditions for use cases that involve LLMs performing file operations.

Structured file listing info.

Minimal contract used across backends. Only path is required. Other fields are best-effort and may be absent depending on backend.

A non-matching line surrounding a grep match, used for context_lines.

A single match from a grep search.

Data structure for storing file contents with metadata.

Result from backend read operations.

Result from backend write operations.

Result from backend edit operations.

Result from backend delete operations.

Result from backend ls operations.

Result from backend grep operations.

Result from backend glob operations.

Result of code execution.

Simplified schema optimized for LLM consumption.

Result of BaseSandbox.execute_with_offload.

offloaded describes the capture mechanism and is kept off ExecuteResponse (which an ordinary execute never sets).

Extension of BackendProtocol that adds shell command execution.

Designed for backends running in isolated environments (containers, VMs, remote hosts).

Adds execute()/aexecute() for shell commands and an id property.

See BaseSandbox for a base class that implements all inherited file operations by delegating to execute().

Protocol for pluggable memory backends (single, unified).

Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.

File operations (grep, glob, ls, read, etc.) live on this base protocol rather than only on SandboxBackendProtocol because not every backend has a shell. StateBackend and StoreBackend store files in in-memory state or a remote store with no process to exec into, so they implement grep/glob in pure Python and have no execute at all. Even on shell-capable backends, the tools are not just convenience wrappers around execute: they enforce literal-only matching (not regex), return structured GrepResult/GlobResult objects, support max_count truncation, and pass through filesystem permission rules — none of which raw execute + shell grep/find provides. Agent-facing prompt guidance should therefore recommend these tools only when they are actually registered, and never assume a shell is available as a fallback.

All file data is represented as dicts with the following structure:

{
    "content": str,  # Text content (utf-8) or base64-encoded binary
    "encoding": str,  # "utf-8" for text, "base64" for binary data
    "created_at": str,  # ISO format timestamp
    "modified_at": str,  # ISO format timestamp
}